Create a NG-CHM • NGCHMR

This vignette demonstrates how to construct a simple NG-CHM, export it to a file, and embed it into RMarkdown.

The required packages can be installed with:

install.packages("NGCHM")
install.packages("NGCHMDemoData", repos = c("https://md-anderson-bioinformatics.r-universe.dev", "https://cloud.r-project.org"))
install.packages("NGCHMSupportFiles", repos = c("https://md-anderson-bioinformatics.r-universe.dev", "https://cloud.r-project.org"))
install.packages("htmltools") # used to embed the NG-CHM into RMarkdown

R Code Example

The following R code demonstrates how to create a NG-CHM from the TCGA breast cancer data, export it to a file, and embed it into an Rmarkdown document. For use by the NGCHM package, the data must be formatted such that:

The heat map data is a matrix with rownames and colnames
The covariate data is a named vector.
- For a row/column covariate, at least one name must be in the row/colnames of the heat map matrix data.

matrix_data_file <- system.file("extdata", "TCGA.BRCA.Expression.csv", package = "NGCHMDemoData")
matrix_data <- as.matrix(read.csv(matrix_data_file, header = TRUE, row.names = 1, check.names = FALSE))
covariate_data_file <- system.file("extdata", "TCGA.BRCA.TP53Mutation.csv", package = "NGCHMDemoData")
covariate_data <- as.matrix(read.csv(covariate_data_file, row.names = 1))
covariate_vector <- as.vector(covariate_data) # create vector of mutation data
names(covariate_vector) <- rownames(covariate_data) # set the names
library(NGCHM)
hm <- chmNew("TCGA BRCA Expression", matrix_data)
covariateBar <- chmNewCovariate("TP53 Mutation", covariate_vector)
hm <- chmAddCovariateBar(hm, "column", covariateBar)
library(NGCHMSupportFiles) # required for chmExportToHTML and chmExportToFile
chmExportToHTML(hm, "tcga-brca.html", overwrite = TRUE)
chmExportToFile(hm, "tcga-brca.ngchm", overwrite = TRUE)
library("htmltools")
filePath <- paste(getwd(), "/tcga-brca.html", sep = "")
htmltools::tags$iframe(src = filePath, width = "100%", height = 700)

Explanation of R Code Example

NGCHMDemoData Package

This vignette uses an additional package of demo data, NGCHMDemoData, which can be installed from our R-Universe repository.

The sample data includes a matrix of gene expression data containing 3437 genes (rows) and 200 samples (columns) of breast cancer data from The Cancer Genome Atlas (TCGA).

TCGA.BRCA.Expression.csv snippet
	TCGA-AO-A0JJ-01A	TCGA-E9-A1R4-01A	TCGA-E9-A6HE-01A	TCGA-E2-A1L9-01A	…
TSPAN6	11.838	9.483	11.157	11.536	…
CFH	12.033	10.835	10.824	12.878	…
ENPP4	11.372	10.749	9.721	11.008	…
SEMA3F	12.722	12.393	13.338	12.451	…
…	…	…	…	…	…

IMPORTANT: In order to be used as the basis for an NG-CHM, a matrix should have both rownames and colnames.

The sample data also includes a vector of TP35 mutation status for the TCGA samples in the matrix. This data will be used to construct a covariate bar.

TCGA.BRCA.TP53Mutation.csv snippet
	MutationState
TCGA-AO-A0JJ-01A	WT
TCGA-E9-A1R4-01A	WT
TCGA-E9-A6HE-01A	WT
TCGA-E2-A1L9-01A	WT
TCGA-E9-A245-01A	WT
TCGA-AO-A0JG-01A	WT
TCGA-C8-A1HE-01A	WT
TCGA-C8-A12W-01A	MUT
…	…

IMPORTANT: In order to be used as the basis for a row/column covariate bar, the data should be formatted as a named vector with at least one name in common with the col/rownames of the matrix.

The NGCHMDemoData package includes these datasets as .csv file. The expression data should be formatted as a matrix with row and column names. The covariate data should be formatted as a named vector. Because this covariate data is a column covariate, the names of the vector match the colnames of the matrix.

library(NGCHMDemoData)
# Read in the expression data, and convert to a matrix
matrix_data_file <- system.file("extdata", "TCGA.BRCA.Expression.csv", package = "NGCHMDemoData")
matrix_data <- as.matrix(read.csv(matrix_data_file, header = TRUE, row.names = 1, check.names = FALSE))
# Read in the mutation data, and format as a named vector
covariate_data_file <- system.file("extdata", "TCGA.BRCA.TP53Mutation.csv", package = "NGCHMDemoData")
covariate_data <- as.matrix(read.csv(covariate_data_file, row.names = 1))
covariate_vector <- as.vector(covariate_data) # create vector of mutation data
names(covariate_vector) <- rownames(covariate_data) # set the names

Creating a NG-CHM

The chmNew() function creates the NG-CHM object. The first argument is the name of the NG-CHM, and the second argument is the matrix data.

library(NGCHM)
hm <- chmNew("TCGA BRCA Expression", matrix_data)

A covariate bar can be created with chmNewCovariate(). The first argument is the name of the covariate, and the second argument is the named vector of covariate data. The chmAddCovariateBar() function adds the covariate bar to the NG-CHM. The first argument is the NG-CHM, the second argument is the type of covariate bar (‘column’ or ‘row’), and the third argument is the covariate bar object.

covariateBar <- chmNewCovariate("TP53 Mutation", covariate_vector)
hm <- chmAddCovariateBar(hm, "column", covariateBar)

Export to File

The NG-CHM can be exported to two different file types:

An HTML file that can be emailed to collaborators, opened in a web browser, or embedded in an RMarkdown file.
A ‘.ngchm’ file that can be opened in the [NGCHM Viewer]https://www.ngchm.net/Downloads/ngChmApp.html).

Both methods use files from the NGCHMSupportFiles package. When loaded, NGCHMSupportFiles sets environment variables pointing to these additional files.

library(NGCHMSupportFiles)
#> Environment variable SHAIDYMAPGEN set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/java/ShaidyMapGen.jar
#> Environment variable NGCHMWIDGETPATH set to /Users/runner/work/_temp/Library/NGCHMSupportFiles/js/ngchmWidget-min.js

1. Export to HTML

The NG-CHM can be exported as an HTML file with the chmExportToHTML() function. The first argument is the NG-CHM created above. The second argument is the desired filename. Here we also use overwrite=TRUE to overwrite the file if it already exists.

chmExportToHTML(hm, "tcga-brca.html", overwrite = TRUE)

The file ‘tcga-brca.html’ can be shared with collaborators and opened in a web browser.

2. Export to .ngchm File

Alternatively, .ngchm file can be created with the chmExportToFile() function.

chmExportToFile(hm, "tcga-brca.ngchm", overwrite = TRUE)

The file ‘tcga-brca.ngchm’ can be opened in the NG-CHM Viewer. IMPORTANT: The filename must end with ‘.ngchm’ to open in the NG-CHM Viewer.

Embed into RMarkdown

The .html file can be embedded into RMarkdown via htmltools::includeHTML():

library('htmltools')
filePath = paste(getwd(),'/tcga-brca.html',sep='')
htmltools::includeHTML(filePath)
#> Warning: `includeHTML()` was provided a `path` that appears to be a complete HTML document.
#> ✖ Path: /Users/runner/work/NGCHM-R/NGCHM-R/vignettes/tcga-brca.html
#> ℹ Use `tags$iframe()` to include an HTML document. You can either ensure `path` is accessible in your app or document (see e.g. `shiny::addResourcePath()`) and pass the relative path to the `src` argument. Or you can read the contents of `path` and pass the contents to `srcdoc`.